package com.harmony.pilot.completion.service;

import java.util.Optional;
import java.util.concurrent.CompletableFuture;
import java.util.function.Supplier;

/**
 * 缓存服务接口
 * 提供查询结果缓存和性能优化
 */
public interface CacheService {
    
    /**
     * 获取缓存值
     * 
     * @param key 缓存键
     * @param type 值类型
     * @return 缓存值（如果存在）
     */
    <T> Optional<T> get(String key, Class<T> type);
    
    /**
     * 设置缓存值
     * 
     * @param key 缓存键
     * @param value 值
     * @param ttlSeconds 过期时间（秒）
     */
    <T> void put(String key, T value, int ttlSeconds);
    
    /**
     * 删除缓存
     * 
     * @param key 缓存键
     */
    void evict(String key);
    
    /**
     * 清除所有缓存
     */
    void clear();
    
    /**
     * 获取或计算（如果缓存不存在）
     * 
     * @param key 缓存键
     * @param supplier 值提供者
     * @param ttlSeconds 过期时间（秒）
     * @return 值
     */
    <T> T getOrCompute(String key, Supplier<T> supplier, int ttlSeconds);
    
    /**
     * 异步获取或计算
     * 
     * @param key 缓存键
     * @param supplier 值提供者
     * @param ttlSeconds 过期时间（秒）
     * @return 异步值
     */
    <T> CompletableFuture<T> getOrComputeAsync(String key, Supplier<T> supplier, int ttlSeconds);
}

